Skip to main content

Known Limitations

This page documents the current limitations of web3agent v0.4.0. Understanding these constraints upfront saves debugging time.

Explorer Tools: 8-Chain Coverage Only

The blockscout_* family of tools relies on the Blockscout indexer, which is only available on 8 of the 17 supported chains:

Supported: Ethereum, Base, Arbitrum, Optimism, Polygon, Gnosis, Scroll, zkSync Era

Not supported: Linea, BSC, Avalanche, Mode, Blast, Mantle, Celo, Sepolia, Base Sepolia

On unsupported chains, any blockscout_* tool call returns a BLOCKSCOUT_NOT_SUPPORTED error. For live on-chain reads (balances, contract calls), use the evm_* tools instead — those work on all 17 chains.

No Browser Wallet Signing Over MCP

The MCP server runs as a local process and cannot open browser wallet prompts (MetaMask, Rabby, etc.). This means:

  • Preparation works: prepareSwapIntent, prepareBridgeIntent, and similar functions can generate EIP-712 data structures over MCP.
  • Signing does not: The actual signing step requires a browser wallet or a server-side private key.

For browser-wallet flows, the typical pattern is: MCP prepares the intent data, the frontend application handles signing via wagmi or ethers.js, then the signed payload is submitted back through the API.

For fully autonomous operation, set PRIVATE_KEY or MNEMONIC and use executeSameChainSwap or orbs_swap directly.

0x and CoinGecko Plugins Require API Keys

The 0x swap plugin and CoinGecko price plugin are not active by default. They require API keys:

ZEROX_API_KEY=your_key_here      # activates 0x swap routing
COINGECKO_API_KEY=your_key_here  # activates CoinGecko price data

Without these keys, the corresponding tools are unavailable. The server_status tool shows which integrations are currently loaded.

Legacy Binance Market Tools Deprecated

Earlier versions included Binance-specific market data tools. These are deprecated in v0.4.0. Use the ccxt_* tools instead, which support Binance and dozens of other exchanges through a unified interface.

If you have existing code calling the old Binance tools, migrate to ccxt_get_ticker, ccxt_get_markets, and ccxt_get_balance with exchange: "binance".

ESM Only

web3agent is published as ESM only. CommonJS (require()) is not supported.

All internal imports use the .js extension, even for TypeScript source files. This is required for Node.js ESM compatibility:

// Correct
import { getSwapQuote } from "./swaps.js";

// Wrong — will fail at runtime
import { getSwapQuote } from "./swaps";

If your project uses CommonJS, you'll need to either migrate to ESM or use a dynamic import() call.

stdout Reserved for MCP Protocol

The MCP protocol communicates over stdout. Any code that writes to stdout (including console.log) will corrupt the MCP stream and break the connection.

All logging must go to stderr:

// Correct
process.stderr.write("[my-module] something happened\n");

// Wrong — corrupts MCP stream
console.log("something happened");

This applies to any custom tools or integrations built on top of web3agent.

No Type Suppression

web3agent's codebase has a strict no-suppression policy: no @ts-ignore, no @ts-expect-error, no as any. This is enforced in CI.

Custom integrations that extend web3agent should follow the same convention. Type assertions (as SomeType) are acceptable when the type is genuinely known; suppression comments are not.

Custom RPC Only for Default Chain

RPC_URL applies only to the chain set by CHAIN_ID. There's no mechanism to configure custom RPCs for multiple chains simultaneously. For all non-default chains, web3agent uses its built-in public RPC endpoints.

If you need a private RPC for a specific non-default chain, set CHAIN_ID to that chain and provide RPC_URL, then pass chainId explicitly on calls to other chains.

Minimum Trade Sizes

Orbs Protocol enforces minimum trade sizes:

  • Liquidity Hub swaps: approximately $6-10 minimum. Smaller amounts return a LOW_DOLLAR_VALUE (ldv) error.
  • Spot orders (dTWAP, dLIMIT, stop-loss, take-profit): $30+ recommended for keepers to fill economically. Smaller orders may sit unfilled.

Spot Orders: No Native Input Token

Spot orders (dTWAP, dLIMIT, stop-loss, take-profit) do not accept native tokens (ETH, BNB, MATIC) as the input. The Spot contract requires wrapped versions:

  • Use WETH instead of ETH
  • Use WBNB instead of BNB
  • Use WMATIC instead of MATIC

Native output tokens are supported. You can receive ETH/BNB/MATIC directly from a Spot order.

Liquidity Hub swaps (the standard orbs_swap tool) do accept native input tokens and handle wrapping automatically.

Node.js 22+ Required

web3agent requires Node.js 22 or later. Earlier versions are not supported. Check your version with:

node --version

If you're on an older version, update via nodejs.org or use a version manager like nvm or fnm.